.TH std::optional::emplace 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary"
.SH NAME
std::optional::emplace \- std::optional::emplace

.SH Synopsis
   template< class... Args >                                \fB(1)\fP \fI(since C++17)\fP
   T& emplace( Args&&... args );                                (constexpr since C++20)
   template< class U, class... Args >                           \fI(since C++17)\fP
   T& emplace( std::initializer_list<U> ilist, Args&&...    \fB(2)\fP (constexpr since C++20)
   args );

   Constructs the contained value in-place. If *this already contains a value before
   the call, the contained value is destroyed by calling its destructor.

   1) Initializes the contained value by direct-initializing (but not
   direct-list-initializing) with std::forward<Args>(args)... as parameters.
   2) Initializes the contained value by calling its constructor with ilist,
   std::forward<Args>(args)... as parameters. This overload participates in overload
   resolution only if std::is_constructible<T, std::initializer_list<U>&,
   Args&&...>::value is true.

.SH Parameters

   args...         -        the arguments to pass to the constructor
   ilist           -        the initializer list to pass to the constructor
.SH Type requirements
   -
   T must be constructible from Args... for overload \fB(1)\fP
   -
   T must be constructible from std::initializer_list and Args... for overload \fB(2)\fP

.SH Return value

   A reference to the new contained value.

.SH Exceptions

   Any exception thrown by the selected constructor of T. If an exception is thrown,
   *this does not contain a value after this call (the previously contained value, if
   any, had been destroyed).

.SH Example


// Run this code

 #include <iostream>
 #include <optional>

 struct A
 {
     std::string s;

     A(std::string str) : s(std::move(str)), id{n++} { note("+ constructed"); }
     ~A() { note("~ destructed"); }
     A(const A& o) : s(o.s), id{n++} { note("+ copy constructed"); }
     A(A&& o) : s(std::move(o.s)), id{n++} { note("+ move constructed"); }

     A& operator=(const A& other)
     {
         s = other.s;
         note("= copy assigned");
         return *this;
     }

     A& operator=(A&& other)
     {
         s = std::move(other.s);
         note("= move assigned");
         return *this;
     }

     inline static int n{};
     int id{};
     void note(auto s) { std::cout << "  " << s << " #" << id << '\\n'; }
 };

 int main()
 {
     std::optional<A> opt;

     std::cout << "Assign:\\n";
     opt = A("Lorem ipsum dolor sit amet, consectetur adipiscing elit nec.");

     std::cout << "Emplace:\\n";
     // As opt contains a value it will also destroy that value
     opt.emplace("Lorem ipsum dolor sit amet, consectetur efficitur.");

     std::cout << "End example\\n";
 }

.SH Output:

 Assign:
   + constructed #0
   + move constructed #1
   ~ destructed #0
 Emplace:
   ~ destructed #1
   + constructed #2
 End example
   ~ destructed #2

   Defect reports

   The following behavior-changing defect reports were applied retroactively to
   previously published C++ standards.

     DR    Applied to              Behavior as published               Correct behavior
   P2231R1 C++20      emplace was not constexpr while the required     made constexpr
                      operations can be constexpr in C++20

.SH See also

   operator= assigns contents
             \fI(public member function)\fP
